home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
FishMarket 1.0
/
FishMarket v1.0.iso
/
fishies
/
176-200
/
disk_181
/
tracker
/
readme
< prev
next >
Wrap
Text File
|
1992-05-06
|
6KB
|
127 lines
C Programmer's Amiga Resource Tracking Routines Version 0.0a 1/5/89
-------------------------------------------------------------------------
This code and documentation is released to the Public Domain without any
restrictions on use, resale or redistribution.
No license or warranty of appropriateness, usefulness or bug-freeness is
expressed or implied. This is free code. We don't have a contract.
Written by:
Karl Lehenbauer, Hackercorp, 3918 Panorama, Missouri City, TX, USA 77459
(713) 438-4964 voice, (713) 438-5018 data
Usenet: uunet!sugar!karl, Internet: karl@sugar.uu.net, BIX: kelehen
These routines were written to aid C programmers in insuring that their
programs are properly returning all the memory, signals and locks they
have allocated.
To use them, include tracker.h in your C source programs and recompile.
(The use of an "includes.c" along with the Manx +i and +h flags to
precompile the symbol table obviates the necessity of editing
'#include "tracker.h">' into every one of your source files.)
Next, edit your exit routine to call TrackerExitReport() after it has
freed everything. Then, compile tracker.c using the memory model you're
using for the rest of your code and link your program to include tracker.o.
(This can all be done in your makefile if you've got it set up right.)
Finally, run your program.
The program must either be initiated from the CLI or you must edit your
program's startup code to fopen stderr and direct it somewhere (like
to a window or a file) or you won't get any of the resource tracker's
messages, or worse.
As your program runs, every time it allocs memory via AllocMem(), allocs
a signal via AllocSignal() or gets a Lock via Lock(), special tracking
routines execute instead (thanks to some macros defined by tracker.h)
which, in addition to performing the action you requested, record
information about what you requested and what you got. For AllocMem(),
the source file and line of the AllocMem call as well as the amount of memory
requested and the pointer to the memory returned are recorded. For
AllocSignal(), only the signal numbers allocated are recorded at this time.
For Lock(), the file name to be locked, source file and line number and
the lock returned are recorded.
When your program frees memory via FreeMem(), a special tracking version
of FreeMem is executed that searches the list of entries recorded by the
tracking version of AllocMem(). The resource tracker reports if you free
something more than once, if you free something that you didn't allocate
or if the length that you are freeing differes from what you allocated.
This includes the source file name and line number of the matching AllocMem
(when it is known) and always includes the source file and line for FreeMem.
When your program frees a signal via FreeSignal(), a tracking version
of FreeSignal checks to see if you have allocated the signal you are
now freeing. If you haven't, it reports it, but it doesn't include the
file name and line number at this time. I don't think this is a serious
problem, as signals aren't as critical as the other stuff, but I may add
it in a future version.
When your program unlocks a lock via UnLock(), a tracking version of UnLock
searches the list of recorded locks to see if you locked the lock you are
unlocking and report accordingly.
The tracker exit report provided by TrackerExitReport() is where most of
the bugs are identified. TrackerExitReport identifies all AllocMems that
didn't have a corresponding FreeMem, including the source file and line
of the call to AllocMem as well as the address and size of the memory
in question. The resource tracker does not free the memory for you because
you may have not freed the memory on purpose (for example, you may have
spawned a task that uses it will free it later) and it cannot know that.
The exit report details all signals that weren't freed. This isn't very
important, in my opinion.
Also, the exit report prints information on all file locks that were made
that didn't have a corresponding UnLock. This information includes the
name of the file, value of the lock and the source file and line of the
code that locked it.
The exit report also prints the number of calls to allocate and free memory,
allocate and free signals and to lock and unlock files as a gross indicator
of whether you're cleaning everything up properly.
Note that, in the default configuration, memory that is freed and
reallocated will screw up the tracker because the tracker continues
to track memory objects after they have been freed. This is a tradeoff
between being to be able to detect multiple frees of the same memory or
not. If that's a problem, tracker.c can be recompiled with a
-DFORGET_MEMORY_WHEN_FREED option so that it will not try to detect
multiple frees.
The same is true for the lock tracking routines, although in that case
the argument is more clear that unlocks should cause the lock tracking
entry to be discarded, because multiple unlocks are common and multiple
locks and unlocks of the same file during execution are also conceivably
pretty common. Right now by default, the tracker will track locks after
they have been freed. To change this behavior, recompile tracker.c with
the -DFORGET_LOCKS_WHEN_UNLOCKED option.
Unfortunately, the tracker macros that redefine AllocMem and such will
cause your compiler to barf on any files you have that declare them
as external. If that happens, either remove the external declarations
(and include <functions.h>) or move them to be before the include of
tracker.h.
ALPHA RELEASE, SOFTWARE STATUS
------------------------------
The Lock, Unlock and DupLock tracking routines have not been tested
adequately. The signal stuff works OK, but that's no biggie. The
main thing of interest is the tracking AllocMem and FreeMem, which
I have used successfully on several programs that I have been working
on.
-karl @ The Hacker's Haven, Houston, TX -- 5-Jan-89
P.S. Note that TrackerExitReport() must be called to get the tracking
routines to free the memory they have allocated, so it's a good idea
to call it from your abnormal exit (_abort, etc) routines as well as
normal exit. Also, that's good because you can make sure you're freeing
properly from your strange abort conditions, a thing that's hard to get
right.